<para>
A #GdkWindow is a rectangular region on the screen. It's a low-level object,
used to implement high-level objects such as #GtkWidget and #GtkWindow on the
-GTK+ level. A #GtkWindow is a toplevel window, the thing a user might think of
-as a "window" with a titlebar and so on; a #GtkWindow may contain many #GdkWindow.
+GTK+ level. A #GtkWindow is a toplevel window, the thing a user might think of
+as a "window" with a titlebar and so on; a #GtkWindow may contain many #GdkWindow.
For example, each #GtkButton has a #GdkWindow associated with it.
</para>
+<refsect2 id="COMPOSITED-WINDOWS"><title>Composited Windows</title>
+<para>
+Normally, the windowing system takes care of rendering the contents of a child
+window onto its parent window. This mechanism can be intercepted by calling
+gdk_window_set_composited() on the child window. For a
+<firstterm>composited</firstterm> window it is the responsibility of the
+application to render the window contents at the right spot.
+</para>
<example id="composited-window-example"><title>Composited windows</title>
<programlisting><![CDATA[
#include <gtk/gtk.h>
* this handler is called after the red has been drawn. If it was
* called before then GTK would just blindly paint over our work.
*
- * Note: if the child window has children, then you need a cairo 1.16
+ * Note: if the child window has children, then you need a cairo 1.6
* feature to make this work correctly.
*/
static gboolean
]]>
</programlisting></example>
<para>
-In the example <xref linkend="composited-window-example"/>, a button is
-placed inside of an event box inside of a window. The event box is
-set as composited and therefore is no longer automatically drawn to
-the screen.
+In the example <xref linkend="composited-window-example"/>, a button is
+placed inside of an event box inside of a window. The event box is
+set as composited and therefore is no longer automatically drawn to
+the screen.
</para>
<para>
When the contents of the event box change, an expose event is
<para>
In our case, we merge the contents with a 50% transparency. We
also set the background colour of the window to red. The effect is
-that the background shows through the button.
+that the background shows through the button.
+</para>
+</refsect2>
+<refsect2 id="OFFSCREEN-WINDOWS"><title>Offscreen Windows</title>
+<para>
+Offscreen windows are more general than composited windows, since they
+allow not only to modify the rendering of the child window onto its parent,
+but also to apply coordinate transformations.
+</para>
+<para>
+To integrate an offscreen window into a window hierarchy, one has to call
+gdk_window_set_embedder() and handle a number of signals. The
+gdk_offscreen_window_set_embedder() and handle a number of signals. The
+#GdkWindow::pick-embedded-child signal on the embedder window is used to
+select an offscreen child at given coordinates, and the #GdkWindow::to-embedder
+and #GdkWindow::from-embedder signals on the offscreen window are used to
+translate coordinates between the embedder and the offscreen window.
</para>
+</refsect2>
<!-- ##### SECTION See_Also ##### -->
<para>
* @window: a #GdkWindow
* @embedder: the #GdkWindow that @window gets embedded in
*
+ * Sets @window to be embedded in @embedder.
+ *
+ * To fully embed an offscreen window, in addition to calling this
+ * function, it is also necessary to handle the #GdkWindow::pick-embedded-child
+ * signal on the @embedder and the #GdkWindow::to-embedder and
+ * #GdkWindow::from-embedder signals on @window.
+ *
* Since: 2.18
*/
void
* The ::pick-embedded-child signal is emitted to find an embedded
* child at the given position.
*
- * Returns: the GdkWindow of the embedded child at @x, @y, or %NULL
+ * Returns: the #GdkWindow of the embedded child at @x, @y, or %NULL
*
* Since: 2.18
*/
* The ::to-embedder signal is emitted to translate coordinates
* in an offscreen window to its embedder.
*
+ * See also #GtkWindow::from-embedder.
+ *
* Since: 2.18
*/
signals[TO_EMBEDDER] =
* The ::from-embedder signal is emitted to translate coordinates
* in the embedder of an offscreen window to the offscreen window.
*
+ * See also #GtkWindow::to-embedder.
+ *
* Since: 2.18
*/
signals[FROM_EMBEDDER] =
* Return value: list of toplevel windows, free with g_list_free()
*
* Deprecated: 2.16: Use gdk_screen_get_toplevel_windows() instead.
- **/
+ */
GList *
gdk_window_get_toplevels (void)
{
/**
* gdk_window_get_cursor:
* @window: a #GdkWindow
- * @cursor: a cursor
*
* Retrieves a #GdkCursor pointer for the cursor currently set on the
* specified #GdkWindow, or %NULL. If the return value is %NULL then
* @src_y: y position in @window
* @dest_x: x position in @drawable
* @dest_y: y position in @drawable
- * @width: width of redirection
- * @height: height of redirection
+ * @width: width of redirection, or -1 to use the width of @window
+ * @height: height of redirection or -1 to use the height of @window
*
* Redirects drawing into @window so that drawing to the
* window in the rectangle specified by @src_x, @src_y,
static void
from_embedder (GdkWindowObject *window,
- double embedder_x, double embedder_y,
- double *offscreen_x, double *offscreen_y)
+ gdouble embedder_x,
+ gdouble embedder_y,
+ gdouble *offscreen_x,
+ gdouble *offscreen_y)
{
g_signal_emit (window,
signals[FROM_EMBEDDER], 0,
static void
convert_coords_to_child (GdkWindowObject *child,
- double x, double y,
- double *child_x, double *child_y)
+ gdouble x,
+ gdouble y,
+ gdouble *child_x,
+ gdouble *child_y)
{
if (gdk_window_is_offscreen (child))
{
static gboolean
point_in_window (GdkWindowObject *window,
- double x, double y)
+ gdouble x,
+ gdouble y)
{
return
x >= 0 && x < window->width &&
static GdkWindow *
convert_native_coords_to_toplevel (GdkWindow *window,
- double child_x, double child_y,
- double *toplevel_x, double *toplevel_y)
+ gdouble child_x,
+ gdouble child_y,
+ gdouble *toplevel_x,
+ gdouble *toplevel_y)
{
GdkWindowObject *private = (GdkWindowObject *)window;
gdouble x, y;
static GdkWindowObject *
pick_embedded_child (GdkWindowObject *window,
- double x, double y)
+ gdouble x,
+ gdouble y)
{
GdkWindowObject *res;
GdkWindow *
_gdk_window_find_child_at (GdkWindow *window,
- int x, int y)
+ int x,
+ int y)
{
GdkWindowObject *private, *sub;
double child_x, child_y;
GdkWindow *
_gdk_window_find_descendant_at (GdkWindow *toplevel,
- double x, double y,
- double *found_x,
- double *found_y)
+ gdouble x,
+ gdouble y,
+ gdouble *found_x,
+ gdouble *found_y)
{
GdkWindowObject *private, *sub;
- double child_x, child_y;
+ gdouble child_x, child_y;
GList *l;
gboolean found;
projects / gtk4.git / commitdiff